Vue CLIで作成したプロジェクトにTypeDocを導入する
こんにちは。サービスグループの武田です。
プログラムのドキュメントを生成する手法のひとつとして、ソースコードにコメントを書き、ツールでドキュメントをビルドするという方法があります。Javaなどの言語では標準でツールが提供されています。今回はTypeScriptのドキュメントを生成したいなと思い調べたところ、TypeDocが良さそうだったのでVueプロジェクトに導入してみました。TypeDocはMarkdownが使えるのもイマドキです。
環境
今回の検証環境は次のような環境になっています。
$ node -v v10.16.0 $ vue -V 3.9.3 $ sw_vers ProductName: Mac OS X ProductVersion: 10.14.5 BuildVersion: 18F132
そのほか、主なモジュールのバージョンは以下となっています。また、vueコマンドがインストールされていない場合は、npm install -g @vue/cliでインストールします。
プロジェクトを作成
まずはVue CLIを利用してプロジェクトを作成します。
$ vue create example-vue-typedoc
presetはManualにして、Linter以外はすべてデフォルトを選択します。LinterはESLintを選択しています。
最後の項目を選択するとインストールが始まります。インストールが終わったら、準備完了です。
今回のソースコード全体はGitHubに上げてあります。
Exampleクラスを書いてドキュメントを生成してみる
まずは次のようなクラスを作ってみます。内容は特にありません。
/**
* TypeDocのExampleです。
*/
export default class Example {
/** プロパティです。 */
public message: string = 'Hello';
/**
* メソッドです。
* @returns メッセージ
*/
public sayMessage(): string {
return this.message;
}
}
続いてTypeDocをインストールします。
$ npm install -D typedoc
インストールできたら、さっそくドキュメントを生成してみましょう。オプションがいろいろありますが、詳細は公式のリファレンスを参照してください。ここでは一番シンプルにやってみます。
$ ./node_modules/.bin/typedoc --out docs src/ $ open docs/index.html
不要なファイルのドキュメントも出力されてますが、とりあえずは成功と言えそうです。
TypeDocをwebpackと連携させる
Vue CLIで作成したプロジェクトは内部的にwebpackを使用しています。またTypeDocにはwebpackと連携させるためのプラグインが提供されています。つまり、Vue CLIのプロジェクトにプラグインを導入することで、簡単にドキュメントの生成ができます。
それでは連携させていきます。次のコマンドでtypedoc-webpack-pluginをインストールします。
$ npm install -D typedoc-webpack-plugin
次にwebpackの設定をします。Vue CLIで作成したプロジェクトでは、プロジェクトルート直下にvue.config.jsを用意することでオートロードされます。プラグインの引数でTypeDocのオプションを細かく指定できます。
const TypedocWebpackPlugin = require('typedoc-webpack-plugin');
module.exports = {
configureWebpack: {
plugins: [
new TypedocWebpackPlugin({
name: 'example-vue-typedoc',
mode: 'file',
includeDeclarations: false,
ignoreCompilerErrors: true,
excludeNotExported: true,
}, './src/'),
],
},
};
それではプロジェクトをビルドします。ビルドすると自動的にドキュメントも生成されます。
$ npm run build $ open dist/docs/index.html
すっきりとしたドキュメントが生成されました！
まとめ
多人数での開発ではもちろんですが、個人での開発でも、明日の自分のためにドキュメントを書いておくのが好ましいです。またJavaScriptと違い、型定義を自分でコメントに書く必要がないのでTypeScriptとTypeDoc最高ですね。
